A5.runChain Method
Syntax
Arguments
- actionsArray of Functions
An array containing the functions to be executed. Some or all of the functions in the array may be asynchronous.
- onAllDoneFunction
Function to call when all of the functions in the actions array have completed.
- onStopFunction
Function to call if any of the function in the actions array stopped the execution chain.
- contextObject
An optional object to define the scope of the actions. Inside each function that is executed, the this object will be the same as the context. This allows you to pass initial information into the first function and allows each function to set variables on the this object that will be seen by subsequent functions.
Description
Run a series of JavaScript functions synchronously.
Discussion
The A5.runChain() function can be used to run a set of asynchronous JavaScript functions synchronously.
Many JavaScript functions run asynchronously. For example, functions that make Ajax callbacks are asynchronous. In Cordova applications, most of the functions are asynchronous.
This helper function allows you to run a series of functions (some of which may be asynchronous) synchronously (i.e. the second function does not start executing until the first function has completed, and so on).
Each function in the actions array must take a single object as its input parameter. Each function must call the .next() method of the input object to begin execution of the next function in the actions array. If the function is an asynchronous function, the call to the .next() method would be in the onSuccess callback of the asynchronous function.
The execution chain can be stopped if any function calls the input object's .stop() method.
Example:
//define 3 functions you want to run asynchronously
//this is an asynchronous function
function action1(obj) {
setTimeout(function() {
console.log('wait 1 second');
obj.next() // call the next function to be executed
},1000 );
}
function action2(obj) {
console.log('this is a synchronous function');
obj.next()
}
function action3(obj) {
setTimeout(function() {
console.log('wait .5 seconds');
obj.next()
},500 );
}
//create an array with the functions to executed
var actions = [action1,action2,action3];
//run the actions synchronously
A5.runChain(actions,
function() { alert('alldone'); },
function(err) { alert('error: ' + err); }
);
//if we want to pass in values to the chain we can do as follows
var context = {var1: 'value of var1'};
A5.runChain(actions,
function() { alert('alldone'); },
function(err) { alert('error: ' + err); },
context
);
//inside any of the functions we can reference 'this.var1'
//we can also set properties on the 'this' object.When you run this code, the messages in the console will appear in the following order:
wait 1 second this is a synchronous function wait .5 seconds
If you had simply called the functions one after the other, then the messages would have appeared in the following order:
this is a synchronous function wait .5 seconds wait 1 second
Videos
Check out the videos below to learn more.
Running Asynchronous Functions Synchronously
Many Javascript functions in an application are asynchronous. For example, functions that make Ajax callbacks are asynchronous and many Cordova functions are also asynchronous. Often you will want to call several asynchronous functions, but you want to execute the functions synchronously. For example, you do not want to call the second function until the first function has completed.
Javascript Promises are typically used to run asynchronous code synchronously. But Promises can be hard to understand and it can be tricky to restructure your code to use Promises. The Alpha Anywhere Javascript library has a function called A5.runChain() that provide an easy way to run asynchronous functions synchronously. Also, minimal changes need be made to your function definitions to make them suitable for use with the A5.runChain() function.
In this video we show how the A5.runChain() function is used.
See Also